# source.transformImport

- **类型：**

```ts
type TransformImport =
  | false
  | Array<{
      libraryName: string;
      libraryDirectory?: string;
      style?: string | boolean;
      styleLibraryDirectory?: string;
      camelToDashComponentName?: boolean;
      transformToDefaultImport?: boolean;
      customName?: string;
      customStyleName?: string;
    }>;
```

- **默认值：** `undefined`

转换 import 的路径，可以用于模块化引用三方包的子路径，能力类似于 [babel-plugin-import](https://npmjs.com/package/babel-plugin-import)。

## 示例

### 按需引入 antd 组件

在使用 [antd](https://github.com/ant-design/ant-design) 组件库时（低于 v5 版本），你可以通过以下配置来按需引入组件：

```js
export default {
  source: {
    transformImport: [
      {
        libraryName: 'antd',
        libraryDirectory: 'es',
        style: 'css',
      },
    ],
  },
};
```

源代码如下：

```js
import { Button } from 'antd';
```

会被转换成：

```js
import Button from 'antd/es/button';
import 'antd/es/button/style';
```

### 按需引入 lodash

在使用 lodash 时，你可以通过 `transformImport` 来自动引用子路径，减小包体积。

```js
export default {
  source: {
    transformImport: [
      {
        libraryName: 'lodash',
        customName: 'lodash/{{ member }}',
      },
    ],
  },
};
```

源代码如下：

```js
import { get } from 'lodash';
```

会被转换成：

```js
import get from 'lodash/get';
```

请避免以下用法，否则会引入所有的 lodash 代码：

```js
import _ from 'lodash';
import lodash from 'lodash';
```

## 适用范围

`transformImport` 只适用于经过 Rsbuild 编译的模块。需要注意的是，Rsbuild 默认并不会编译位于 node_modules 目录下的 JavaScript 文件。这意味着，node_modules 目录内的代码将不会被 `transformImport` 处理。

如果你希望通过 `transformImport` 对 node_modules 下的代码进行处理，请将相关模块添加到 [source.include](/config/source/include) 配置中。

```ts
export default {
  source: {
    include: [/[\\/]node_modules[\\/]some-package[\\/]/],
  },
};
```

## 选项

### libraryName

- **类型：** `string`

用于指定需要按需加载的模块名称。当 Rsbuild 遍历代码时，如果遇到了对应模块的 import 语句，则会对其进行转换。

### libraryDirectory

- **类型：** `string`
- **默认值：** `'lib'`

用于拼接转换后的路径，拼接规则为 `${libraryName}/${libraryDirectory}/${member}`，其中 member 为引入成员。

示例：

```ts
import { Button } from 'foo';
```

转换结果:

```ts
import Button from 'foo/lib/button';
```

### style

- **类型：** `boolean`
- **默认值：** `undefined`

确定是否需要引入相关样式，若为 `true`，则会引入路径 `${libraryName}/${libraryDirectory}/${member}/style`。若为 `false` 或 `undefined` 则不会引入样式。

当配置为 `true` 时：

```ts
import { Button } from 'foo';
```

转换结果:

```ts
import Button from 'foo/lib/button';
import 'foo/lib/button/style';
```

### styleLibraryDirectory

- **类型：** `string`
- **默认值：** `undefined`

该配置用于拼接引入样式时的引入路径，若该配置被指定，则 `style` 配置项会被忽略。拼接引入路径为 `${libraryName}/${styleLibraryDirectory}/${member}`。

当配置为 `styles` 时：

```ts
import { Button } from 'foo';
```

转换结果:

```ts
import Button from 'foo/lib/button';
import 'foo/styles/button';
```

### camelToDashComponentName

- **类型：** `boolean`
- **默认值：** `true`

是否需要将 camelCase 的引入转换成 kebab-case。

示例：

```ts
import { ButtonGroup } from 'foo';
```

转换结果：

```ts
// 设置成 true：
import ButtonGroup from 'foo/button-group';
// 设置成 false：
import ButtonGroup from 'foo/ButtonGroup';
```

### transformToDefaultImport

- **类型：** `boolean`
- **默认值：** `true`

是否将导入语句转换成默认导入。

示例：

```ts
import { Button } from 'foo';
```

转换结果：

```ts
// 设置成 true：
import Button from 'foo/button';
// 设置成 false：
import { Button } from 'foo/button';
```

### customName

- **类型：** `string`
- **默认值：** `undefined`

自定义转换后的导入路径。

比如下面的配置，会将 `import { foo } from 'my-lib'` 转换为 `import foo from 'my-lib/foo'`。

```js
export default {
  source: {
    transformImport: [
      {
        libraryName: 'my-lib',
        customName: `my-lib/{{ member }}`,
      },
    ],
  },
};
```

此外，你还可以声明转换后的路径格式，例如设置为 `my-lib/{{ camelCase member }}`，来将 member 转换成驼峰格式。

支持以下格式：

- `kebabCase`：字母小写，单词之间使用连字符连接。例如：`my-variable-name`。
- `snakeCase`：字母小写，单词之间使用下划线连接。例如：`my_variable_name`。
- `camelCase`：首字母小写，随后每个单词的首字母大写。例如：`myVariableName`。
- `upperCase`：字母大写，其他字符不变。例如：`MY-VARIABLE-NAME`。
- `lowerCase`：字母小写，其他字符不变。例如：`my-variable-name`。

### customStyleName

- **类型：** `string`
- **默认值：** `undefined`

自定义转换后的样式导入路径，用法与 `customName` 一致。
